namespace Sage.CloudStorage.Qiniu.Auth
{
    /// <summary>
    /// 七牛云认证类型枚举
    /// 定义不同API场景下使用的认证方式
    /// </summary>
    /// <remarks>
    /// 七牛云提供多种认证方式，针对不同的API场景：
    /// - 管理API：用于存储桶和文件管理操作
    /// - 上传API：用于文件上传操作
    /// - 下载API：用于私有文件下载
    /// - 流管理API：用于直播流管理
    /// 
    /// 选择合适的认证类型对于API调用成功至关重要
    /// </remarks>
    public enum QiniuAuthType
    {
        /// <summary>
        /// 管理API认证 (QBox格式) - 传统认证方式
        /// </summary>
        /// <remarks>
        /// 使用场景：
        /// - 早期版本的存储桶管理API
        /// - 部分兼容性要求的文件管理API
        /// - 统计查询API的旧版本
        /// 
        /// 格式：Authorization: QBox AccessKey:签名
        /// 签名算法：对URL路径+查询参数+请求体进行HMAC-SHA1签名
        /// </remarks>
        ManageApi,

        /// <summary>
        /// 管理API认证V2 (Qiniu格式) - 推荐的新版本认证方式
        /// </summary>
        /// <remarks>
        /// 使用场景：
        /// - 新版存储桶管理API（推荐）
        /// - CDN管理API
        /// - 数据处理API
        /// - 大部分七牛云服务的最新版本API
        /// 
        /// 格式：Authorization: Qiniu AccessKey:签名
        /// 签名算法：包含HTTP方法、Host、自定义头部等更多信息，安全性更高
        /// 
        /// 优势：
        /// - 安全性更高，包含更多请求信息
        /// - 支持自定义头部验证
        /// - 符合现代API安全标准
        /// </remarks>
        ManageApiV2,

        /// <summary>
        /// 上传凭证认证 - 用于文件上传场景
        /// </summary>
        /// <remarks>
        /// 使用场景：
        /// - 客户端直传文件到七牛云
        /// - 服务端代理上传文件
        /// - 分片上传文件
        /// - 移动端文件上传
        /// 
        /// 特点：
        /// - 包含上传策略信息
        /// - 支持回调和数据处理
        /// - 可设置文件大小和类型限制
        /// - 有时效性，防止凭证滥用
        /// 
        /// 格式：通常作为表单字段或自定义头部传递
        /// </remarks>
        Upload,

        /// <summary>
        /// 下载凭证认证 - 用于私有文件下载
        /// </summary>
        /// <remarks>
        /// 使用场景：
        /// - 私有存储桶中文件的下载
        /// - 需要访问控制的文件
        /// - 防盗链保护的资源
        /// - 临时分享链接生成
        /// 
        /// 特点：
        /// - 直接修改下载URL，添加签名参数
        /// - 有时效性，过期后URL失效
        /// - 不使用Authorization头部
        /// - 适合浏览器直接访问
        /// 
        /// URL格式：原始URL + ?e=过期时间&amp;token=AccessKey:签名
        /// </remarks>
        Download,

        /// <summary>
        /// 流管理凭证认证 - 用于直播流管理
        /// </summary>
        /// <remarks>
        /// 使用场景：
        /// - 直播流的创建、删除、查询
        /// - 流状态管理和控制
        /// - 录制管理功能
        /// - 截图和水印功能
        /// - 流量统计和分析
        /// 
        /// 特点：
        /// - 使用Qiniu格式的Authorization头
        /// - 对请求体进行带数据签名
        /// - 主要用于POST/PUT等写操作
        /// - 签名包含完整的请求体内容
        /// 
        /// 格式：Authorization: Qiniu AccessKey:签名
        /// </remarks>
        StreamManage
    }
}
